home *** CD-ROM | disk | FTP | other *** search
/ PC World Interactive 7 / PC World Interactive 7.iso / program / cprog.EXE / OBJ2ASM.ZIP / OBJASM.DOC < prev    next >
Text File  |  1990-12-22  |  20KB  |  397 lines
  1.  
  2.                                O B J A S M
  3.        An object file to assembly language file conversion utility
  4.  
  5. INTRODUCTION
  6. ------------
  7.  
  8.     Under normal compilation procedures, most programs are converted into an
  9. intermediate notation before being converted into executable code.  This 
  10. notation simplifies the process of managing large programs by allowing the
  11. programmer to divide a program into many modules.  When changes are made
  12. to a module, the programmer need only compile that module rather than
  13. the entire program.  For most 80x86 and compatible processors, this notation
  14. is stored in a .OBJ file.
  15.  
  16.     After compilation, the .OBJ file must be converted into a machine 
  17. executable form.  At this stage the various modules must be combined and
  18. any inter-module dependencies must be resolved.  This process is called
  19. linking and is accomplished by LINK, LINK86, or PLINK86 (depending on which
  20. vendor you purchase it from).  In order to accomplish this resolving, the
  21. inter-module dependancy information must be stored in the .OBJ file.  This
  22. information normally consists of routine names, variable names, and other
  23. globally known quantities.
  24.  
  25.     For the most part, once a program has been compiled into its .OBJ file,
  26. there is no going back.  There is no way to convert the .OBJ file back into
  27. its appropriate language.  It is for that reason that many companies who wish
  28. to sell thier proprietary routines to programmers, do so in the .OBJ file
  29. form.  Normally these companies send out a library file (.LIB).  .LIB files
  30. contain one or more .OBJ files. The program which groups .OBJ files into an
  31. .LIB file is known as LIB, LIB86, or PLIB86.  This method of distribution
  32. has made routine vendors happy for many years.
  33.  
  34.     But this distribution of encoded routines has meant headaches for 
  35. programmers.  Programmers who discovered bugs in the routines, or wanted to
  36. make enhancements had to contact the vendor and plead for help.  The 
  37. programmers were at the mercy of the routine vendors.
  38.  
  39.     Fortunately, OBJASM came along.  OBJASM is a utility which can convert
  40. .OBJ files back into assembly language, much like a dis-assembler.  Unlike
  41. a dis-assembler however, OBJASM is able to determine the names of the routines
  42. that it is dis-assembling.  Globally known data names can be determined as
  43. well. OBJASM is also able to determine the segments of the original routines.  
  44. Segments are logical/physical divisions of sections of routines, normal
  45. segments are code, data, stack, etc.  With this additional knowledge, OBJASM
  46. is able to produce an assembly language listing which is easier to read, easier
  47. to understand, and easier to modify than normal dis-assembler output.  
  48.  
  49.     OBJASM output is compatible with MASM version 4.0 or later.  It runs 
  50. under MS-DOS version 3.0 or later although it is able to process .OBJ files
  51. (as specified by INTEL, document order no. 121748-001) from many other 80x86
  52. operating systems such as CPM-86, XENIX 80x86, OS/2 and more.  I believe that
  53. the format for UNIX (it has .o files) is completely different.
  54.  
  55. COMPILING OBJASM
  56. ----------------
  57.  
  58.     OBJASM was written for Microsoft C version 4.0 or later, and there is
  59. a supplied 'make' file for that environment.  To execute the 'make' file,
  60. set-up your Microsoft C environment and go to the directory which contains
  61. the OBJASM source files.  Make sure that you have the Microsoft C utility
  62. programs reachable using your 'PATH' environment variable, and type 'MAKE O'
  63. from the dos prompt.  The compilation will proceed to compile OBJASM for
  64. the large model.
  65.  
  66.     One of the modules (ouinsert.c) will give a compiler warning message, or
  67. may fail depending how picky you have set your compiler.  The message has
  68. something to do with 'casting far pointer to long' or vice-versa.  Make sure
  69. your compiler gives only a warning message and proceeds with the compilation
  70. process.  The warning message can be ignored.  Data structure fanatics: the
  71. program uses threaded balanced binary trees for many internal lists and the
  72. ouinsert module is the insert-into-a-list function.  The root node of each tree
  73. has the tree's height (an integer) stored into one of the structures
  74. pointer type members.  This is non-portable C code, but it's ok for most C
  75. compilers.  These threaded balanced binary tree routines were taken from a
  76. set of generic list handling functions.
  77.  
  78.     The modules contained in OBJASM are as follows:
  79.  
  80. omain.c         main() processes command line and passes through input file
  81. oprocess.c      dis-assembly/dumping controlling routines
  82. odisasm.c       routines to dis-assembly the various kinds of 80x86
  83.                     instructions 
  84. oreport.c       routines to display some of the internal lists (publics and
  85.                     externals)
  86. ooutput.c       routines to display various pieces of the dis-assembled .OBJ
  87.                     routine
  88. orXXXXXX.c      (all except oreport.c) routines to process the various INTEL
  89.                     standard .OBJ record formats
  90. oubuff.c        buffer I/O routines for the input file
  91. ouinsert.c      list insertion routine
  92. oufind.c        list searching routine
  93. ounewtre.c      list creation routine
  94. ouinitre.c      initialize all lists
  95. oufmterr.c      .OBJ format error handling routine
  96. ouget.c         input file formating (into chars,ints,longs,etc) routines
  97. oumalloc.c      internal memory allocation routine (with check for out of
  98.                     memory error)
  99. oustruct.c      assembly language structure routines
  100. oextra.c        additional information file processing routines
  101.  
  102.     In addition, some of the modules (omain for example) have some debugging
  103. statements conditionally compiled.  If OBJASM exhibits strange behavior and 
  104. you wish to trace it down, re-compile these modules with the /DDEBUG option
  105. (for MSC). This will define the preprocessor variable DEBUG, which will
  106. enable the conditionally compiled debugging statements.
  107.  
  108.  
  109. EXECUTING OBJASM
  110. ----------------
  111.  
  112.     OBJASM is executed from the command line as:
  113.  
  114.             OBJASM -options filename
  115.             OBJASM -options filename.OBJ
  116.  
  117. If you are dis-assembling a .LIB file, then you must use your LIB, LIB86, or
  118. PLIB86 utility to extract the .OBJ files.
  119.  
  120. All output is sent to standard output (normally the console), but can be re-
  121. directed using the '>' symbol.  A normal OBJASM execution would look like this:
  122.  
  123.             OBJASM OMAIN >OMAIN.ASM
  124.  
  125. The output would then be stored in the file omain.asm.  Output contains tab
  126. (control-I) characters to seperate the various assembly language columns.
  127. A normal line format would appear as:
  128.  
  129.             [LABEL]: (tab)  [INSTRUCTION] (tab) [OPERANDS] (tab) ;[COMMENT]
  130.  
  131.             start:      mov     ds,ax       ; dummy comment
  132.  
  133.     The options currently available for OBJASM are as follows:
  134.  
  135.  Option                         Description
  136.  ------   ---------------------------------------------------------------
  137.    -4     Make MASM v4.0 compatible output (No retf)
  138.    -a     Add labels for better output (use with EXEOBJ)
  139.    -h     Add hex comments showing bytes dis-assembled
  140.    -r     Make RASM86 compatible output (special segment directives, etc)
  141.    -c     Set the minimum size in a code segment, this option is followed
  142.             by a number which represents the new value. Eg. -c20
  143.    -s     Set the minimum size in a data segment, this option is followed
  144.             by a number which represents the new value. Eg. -s10
  145.    -f     Specifies an additional information file.  The additional information
  146.             file must be given in parenthesis. Eg. -f(myfile)  The additional
  147.             information file's default extension is ".add", as in the example
  148.             above, the file specified would be "myfile.add".  For more
  149.             information see the ADDITIONAL INFORMATION FILE section.
  150.  
  151.  
  152. Technical Information
  153. ---------------------
  154.  
  155.     Most information used in writing OBJASM was taken from the following
  156. public documents:
  157.  
  158.     INTEL 8086 RELOCATABLE OBJECT MODULE FORMATS (Order No. 121748-001)
  159.     MICROSOFT OMF Specification (Dated February 18,1986; this is an edited
  160.                                  copy of the INTEL document)
  161.     MS-DOS ENCYCLOPEDIA
  162.  
  163.     These documents describe the .OBJ file format.  Here is a quick
  164. summarization of the format.   Each .OBJ file contains one or more records.
  165. Each record has a record type (which specifies its purpose), a record length, 
  166. and record data (which depends on the record type). INTEL outlines 30
  167. different record types, most of which are never used.  MICROSOFT added to
  168. these record types and removed the ones which it didn't need.  The record
  169. types which OBJASM supports are listed below.
  170.  
  171.     Record Type   Type Name                 Description
  172.     -----------  -----------    -----------------------------------
  173.         80h         THEADR      Module Header Record
  174.         88h         COMENT      Comment Record
  175.         8Ah         MODEND      End of Module Record
  176.         8Ch         EXTDEF      External Dependancy Definition
  177.         90h         PUBDEF      Public Value Definition
  178.         96h         LNAMES      List of Internally Referenced Names
  179.         98h         GRPDEF      Group Definition
  180.         9Ah         SEGDEF      Segment Definition
  181.         9Ch         FIXUPP      Dependancy Fixing-up Record
  182.         A0h         LEDATA      (Logically) Enumerated Data Record
  183.         A2h         LIDATA      (Logically) Iterated Data Record
  184.         B0h         COMDEF      Communal Value Definition
  185.         B4h         LEXTDEF     Local External Definitions (C static routines)
  186.         B6h         LPUBDEF     Local Public Definitions (??)
  187.         B7h         LPUBDF2     Local Public Definitions (?? Another case? )
  188.         B8h         LCOMDEF     Local Communal Value Definitions (??)
  189.  
  190.     The C modules which handle the records of the above formats are named by
  191. placing the characters "OR" before the type name and have a .C extension.
  192. For example, the module named "ORSEGDEF.C" contains the C routine to handle
  193. the segment definition records.
  194.  
  195.     INTEL defines these other record types which are not supported by OBJASM.
  196.  
  197.     Record Type   Type Name                 Description
  198.     -----------  -----------    -----------------------------------
  199.         6Eh       RHEADR        R-Module Header Record
  200.         70h       REGINT        Register Initialization Record
  201.         72h       REDATA        Relocatable Enumerated Data Record
  202.         74h       RIDATA        Relocatable Iterated Data Record
  203.         76h       OVLDEF        Overlay Definition Record
  204.         78h       ENDREC        End Record
  205.         7Ah       BLKDEF        Block Definition Record
  206.         7Ch       BLKEND        Block End Record
  207.         7Eh       DEBSYM        Debug Symbols Record
  208.         82h       LHEADR        L-Module Header Record
  209.         84h       PEDATA        Physically Enumerated Data Record
  210.         86h       PIDATA        Physically Iterated Data Record
  211.         8Eh       TYPDEF        Type Definition Record
  212.         92h       LOCSYM        Line Numbers Record
  213.         94h       LINNUM        Line Number Record
  214.         A4h       LIBHED        Library Header Record
  215.         A6h       LIBNAM        Library Module Names Record
  216.         A8h       LIBLOC        Library Module Locations Record
  217.         AAh       LIBDIC        Library Value Dictionary
  218.  
  219.     MICROSOFT documents an obsolete method for generating communal records
  220. using the TYPDEF record.  This obsolete method is not handled by OBJASM.
  221.  
  222.  
  223.     The dis-assembler portion of OBJASM is a two pass process.  The first
  224. determines where local labels and symbols need to be placed, and the second
  225. outputs the dis-assembled instructions (with the labels and symbols).
  226.  
  227.     To determine whether to dis-assemble instructions or data, OBJASM performs
  228. a look ahead operation on each byte of the data records.  If the byte is a
  229. printable character, then successive bytes are checked as well.  The main 
  230. module has a two variables called 'code_string' and 'data_string' which are
  231. used to specify the minimum length of a string.  The 'code_string' value
  232. is used in code segments while the 'data_string' value is used in data
  233. segments.  If this minimum length of printable characters is exceeded, then
  234. the bytes will be output as a string.  OBJASM is shipped with a value of 20
  235. for 'code_string' and 3 for 'data_string'.  They work well for most .OBJ files.
  236.  
  237.     Bytes which are not contained in strings are checked against an instruction
  238. lookup and processing routine.  If it is determined that this byte will 
  239. generate a valid instruction, then it is output as an instruction.  All other
  240. bytes are output as simple data bytes.
  241.  
  242.     Some assemblers and compilers will generate .OBJ records which contain
  243. a portion of a string or instruction in one record and the remainder in the
  244. next .OBJ record.  OBJASM does not handle this very well.  Strings spanning
  245. more than one record will be divided. Instructions spanning more than one
  246. record will not be recognized.  Output would look this this:
  247.  
  248. String:
  249.     db  'This is all o'       it should be      db  'This is all one string'
  250.     db  'ne string'
  251.  
  252. Instruction:
  253.     db  0BBh                  it should be      mov bx,MYSYMBOL
  254.  
  255.     dw  MYSYMBOL
  256.  
  257.     OBJASM attempts to accomodates for this by keeping a 16 byte overlap
  258. area.  This overlap area is checked before processing the end of a record.
  259. This helps alleviate the problem for objects which are smaller that 16 bytes,
  260. something which is true for all normal instructions.
  261.  
  262.     For some other interesting quirks in OBJASM, please read the sections
  263. titled "Differences in .OBJ files which cannot be detected" and "Features
  264. allowable in .OBJ format which are not translatable into MASMable code".
  265.  
  266. ADDITIONAL INFORMATION FILE
  267. ---------------------------
  268.     The additional information file, specified with the -f option, is another
  269. method of specifying information to OBJASM.  Lines in this file take one of
  270. the following formats:
  271.  
  272.     Format:                         Example:
  273.       SEG segname segtype               SEG DRIVER CODE
  274.  
  275.     This specifies that the segment named "segname" should be considered
  276. either data or code.  The segtype should be either CODE or DATA indicating
  277. which type is desired. Normally OBJASM determines the segment using the
  278. segment's name, but specifying the segment name and segment type in this
  279. way allows overiding this determination.
  280.  
  281.     Format:                         Example:
  282.       var = segname : offset            TableY = DRIVER : 128
  283.                                         TableX = DRIVER : 200h
  284.  
  285.     This specifies that a label should be placed within the segment "segname"
  286. at the offset "offset".  This can be used to add labels to the dis-assembled
  287. code, and can also be used to overide the internal labels generated by OBJASM.
  288.  
  289.     Format:                         Example:
  290.       segname : offset : datatype       DRIVER : 200h : DW
  291.                                         DRIVER : 202h : DD
  292.  
  293.     This directs OBJASM to avoid the instruction/string look-ahead process
  294. and output data of a specified type.  OBJASM outputs a data directive within
  295. the specified segment named "segname", at the offset "offset".  The "datatype"
  296. can be any of these values: DB, DW, DD, DF, DQ, or DT.  These correspond to
  297. the MASM base data types.
  298.  
  299.     Although this last format allows direct control of how OBJASM outputs
  300. data, care must be taken to put OBJASM into a state where it can actually
  301. use this information.   If OBJASM is processing data as an instuction, it
  302. cannot be directed to output a data directive in the middle of that
  303. instruction.  For example:
  304.  
  305.     Additional information:           .OBJ FILE:
  306.         SOME_SEGMENT: 1 : DW             8B360200   MOV SI,[0002]
  307.  
  308. this would direct OBJASM to output a word in the middle of the MOV instruction.
  309. In-order to accomplish this, the addtional information file would have to
  310. direct that the first byte of the MOV instruction was also a data byte.
  311. To get it to work, you would have to have this:
  312.  
  313.     Additional information:           .OBJ FILE:
  314.         SOME_SEGMENT: 0 : DB             8B         db  08Bh
  315.         SOME_SEGMENT: 1 : DW             3602       dw  0236h
  316.                                          00         ...
  317.  
  318. Other
  319. -----
  320.  
  321.     Yes, there always is a section which defies categorization...
  322. The OBJASM program being continually refined.  If you have any comments about
  323. its execution, wish to add features to it, or need to report a bug(s), please
  324. contact:
  325.  
  326.         Robert F. Day
  327.         19906 Filbert Drive
  328.         Bothell, WA 98012
  329.         (206) 481-8431
  330.  
  331.     The following section is a list of bugs that could not be fixed before
  332. shipping OBJASM.  Please read the bug and problems lists to familiarize
  333. yourself with the known bugs and problem situations.  The design notes are
  334. included to help you help me in refining OBJASM.  If you need (or want) to
  335. add features to OBJASM, please contact me.  We may be working on a similar
  336. addition and we may be able to save you some time.
  337.  
  338. -------------------
  339. Bugs to Dec 14 1990
  340. -------------------
  341.  
  342. 1.  TYPDEF records are ingored (I had some Digital Research Libraries which
  343.     used TYPDEF records, but Microsoft doesn't use them).
  344.  
  345. 2.  Some languages generate segment names which are the same as the names
  346.     of labels within the segment.  MASM won't allow this.  Please rename
  347.     the segment, if possible.
  348.  
  349. --------------------------------------------------
  350. Differences in .OBJ files which cannot be detected
  351. --------------------------------------------------
  352.  
  353. (1) if label2 = label1 + 010h
  354.  
  355.         MOV     AX,label1 + 0010h           ; Might have been like this
  356.  
  357.                     and
  358.  
  359.         MOV     AX,label2                   ; OBJASM will generate this
  360.                                             ; (Evaluates to equivalent address)
  361.  
  362.       Reason: Public labels are resolved in local code before being sent to
  363.               the linker.  Although the .OBJ specifications allow two places
  364.               to store symbol addition information (above, the 0010h), MASM 
  365.               only uses one of them. This is a probable source of some other
  366.               .OBJ differences.  MASM automatically computes the offset of
  367.               the public symbol and creates a fixup record indicating that
  368.               the offset of the segment added to the offset of the public
  369.               within the segment should be used (rather than just a fixup
  370.               indicating that the offset of the public should be used).
  371.  
  372.     Handling: When resolving a reference to an address which is not equal to a
  373.               public symbol, a new local symbol is created.
  374.  
  375.  
  376. -------------------------------------------------------------------------------
  377. Features allowable in .OBJ format which are not translatable into MASMable code
  378. -------------------------------------------------------------------------------
  379.  
  380. (1)   A piece of code like:
  381.  
  382.         DW      _labeln - $             ; Relative (data form of local jmp/call)
  383.  
  384.     Reason:  MASM will not compile the above line.  It is an equivalent data
  385.              representations for relative 'JMP's and 'CALL's
  386.              where _labeln is the label to jump or call to.
  387.  
  388.     Handling: If OBJASM detects this type of code (almost all .OBJ files have
  389.               it) then the data output function will substitute an
  390.               actual value for the $ operator.  This will be noted by a nasty
  391.               comment. The dis-assembly output function will still work if
  392.               they are truly 'JMP's or 'CALL's (Relative addressing is
  393.               proceeded by the jump short or call short opcodes).
  394.  
  395. -----------------
  396. End of OBJASM.DOC
  397.